<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
 * This file contains the PDODB_Function class.
 *
 * PHP version 5
 *
 * This file is part of PEAR::PDODB - A database abstraction layer for PHP5 built
 * using PDO. PHP version 5.1+ is recommended.
 *
 * PEAR::PDODB is free software: you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License as published by the Free
 * Software Foundation, either version 3 of the License, or (at your option)
 * any later version.
 *
 * PEAR::PDODB is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
 * details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with PEAR::PDODB. If not, see <http://www.gnu.org/licenses/>.
 *
 * @package     PDODB
 * @category    Database
 * @author      Lukas Smith <smith@pooteeweet.org>
 * @author      Michael J. I. Jackson <mjijackson@gmail.com>
 * @copyright   1998-2007 Manuel Lemos, Tomas V.V. Cox, Stig S. Bakken, Lukas Smith
 * @copyright   2007 Michael J. I. Jackson
 * @license     http://www.gnu.org/licenses/lgpl-3.0.txt GNU LGPL 3.0
 * @version     SVN: $Id: Function.php 2 2007-11-27 17:20:29Z mjijackson $
 * @link        http://pear.php.net/packages/PDODB
 */

/**
 * The base class for all PDODB function modules.
 *
 * @package     PDODB
 * @category    Database
 * @author      Lukas Smith <smith@pooteeweet.org>
 * @author      Michael J. I. Jackson <mjijackson@gmail.com>
 */
abstract class PDODB_Function extends PDODB_Module
{

    /**
     * Executes a stored procedure and returns the results of the query.
     *
     * @param   string  $name       The name of the function to execute
     * @param   array   $params     An array of parameters to pass the stored
     *                              procedure
     * @return  PDODB_Statement     The resulting statement
     * @access  public
     */
    public function executeStoredProc($name, $params = null)
    {
        $db = $this->getConnection();
        throw new PDODB_UnsupportedFeatureException(__FUNCTION__, $db->driver());
    }

    /**
     * Returns a string that can be used for an internal table when calling
     * only a function.
     *
     * @return  string              SQL string needed for an internal table call
     * @access  public
     */
    public function functionTable()
    {
        return '';
    }

    /**
     * Returns an SQL function call that will generate the current timestamp
     * inside an SQL statement. The $type parameter may be one of the following
     * three values:
     *
     * <ul>
     * <li>timestamp - current date and time, the default</li>
     * <li>date - current date only</li>
     * <li>time - current time only</li>
     * </ul>
     *
     * @param   string  $type       The type of timestamp to return
     * @return  string              The SQL function call
     * @access  public
     */
    public function now($type = 'timestamp')
    {
        switch (strtolower($type)) {
        case 'time':
            return 'CURRENT_TIME';
        case 'date':
            return 'CURRENT_DATE';
        case 'timestamp':
        default:
            return 'CURRENT_TIMESTAMP';
        }
    }

    /**
     * Returns an SQL function call that will generate the substring of a given
     * $value starting at $position and ending after $length characters.
     *
     * @param   string  $value      The string to manipulate
     * @param   int     $position   The starting position of the function call
     * @param   int     $length     The length of the substring
     * @return  string              The SQL function call
     * @access  public
     */
    public function substring($value, $position = 1, $length = null)
    {
        if (!is_null($length)) {
            return "SUBSTRING($value FROM $position FOR $length)";
        }
        return "SUBSTRING($value FROM $position)";
    }

    /**
     * Returns an SQL function call that will concatenate two or more string
     * parameters within an SQL statement. This function accepts an unlimited
     * number of arguments.
     *
     * @return  string              The SQL function call
     * @access  public
     */
    public function concat()
    {
        $args = func_get_args();
        return '(' . implode(' || ', $args) . ')';
    }

    /**
     * Returns an SQL function call that will generate a random float between 0
     * and 1 inside an SQL statement.
     *
     * @return  string              The SQL function call
     * @access  public
     */
    public function random()
    {
        return 'RAND()';
    }

    /**
     * Returns an SQL function call that will convert a string to lower case
     * inside an SQL statement.
     *
     * @param   string  $expression     The string to convert
     * @return  string                  The SQL function call
     * @access  public
     */
    public function lower($expression)
    {
        return "LOWER($expression)";
    }

    /**
     * Returns an SQL function call that will convert a string to upper case
     * inside an SQL statement.
     *
     * @param   string  $expression     The string to convert
     * @return  string                  The SQL function call
     * @access  public
     */
    public function upper($expression)
    {
        return "UPPER($expression)";
    }

    /**
     * Returns an SQL function call that will generate a globally unique
     * identifier within an SQL statement.
     *
     * @return  string              The SQL function call
     * @access  public
     */
    public function guid()
    {
        $db = $this->getConnection();
        throw new PDODB_UnsupportedFeatureException(__FUNCTION__, $db->driver());
    }

}

?>
